Objective

⚠️ Warning: This PR is not meant to be merged by itself. The purpose is to provide a high-level overview of the proposed approach and changes, and to split it into more granular PRs once the approach has been validated.

The goal is to implement Mesh creation for the recently added primitive shapes (#10572), superseding the old set of shapes in bevy_render::mesh::shape. The approach includes a Meshable trait as suggested by the original RFC.

As we rework the mesh shapes, we also have an opportunity to reach some secundary but important goals:

• More shapes: Almost all primitives have mesh creation implemented. This is a lot more than the old set of shapes.
• Document everything: All structs, methods and properties in the shape module are properly documented. The module now has a #![warn(missing_docs)] clause.
• Increase consistency: Some names like "segments" and "resolution" are currently used interchangeably, and APIs aren't very consistent. The default dimensions of shapes are also quite arbitrary. I'm attempting to unify this a bit.
• Different XYZ orientations for 2D shapes: You can now create rectangles, circles, etc. that face the positive or negative X, Y, or Z direction, similarly to Godot's facing direction. This is also useful for the goal below.
• Refactor logic to be more reusable: For example, the bases of cones, cylinders, and so on can use circle meshes instead of always reimplementing the logic.

Closes #10569 (although this might be done across several PRs)

Solution

There is now a Meshable trait:

/// A trait for shapes that can be turned into a [`Mesh`].
pub trait Meshable {
    /// The output of [`Self::mesh`]. This can either be a [`Mesh`]
    /// or a builder used for creating a [`Mesh`].
    type Output;

    /// Creates a [`Mesh`] for a shape.
    fn mesh(&self) -> Self::Output;
}

It's implemented for all of the primitive shapes that support meshing, i.e. currently all of these:

• Capsule
• Circle
• Cone
• ConicalFrustum
• Cuboid
• Cylinder
• Ellipse
• Plane3d
• Rectangle
• RegularPolygon
• Sphere
• Torus
• Triangle2d

Each shape has its own FooMesh version that is returned by the mesh method. These separate structs are required for configuration like specifying the resolution or UV profile, and it uses a builder-like API for ease of use.

For example, the CapsuleMesh, which looks like the current Capsule mesh struct, except it uses the Capsule primitive:

/// A builder used for creating a [`Mesh`] with a [`Capsule`] shape.
#[derive(Clone, Copy, Debug)]
pub struct CapsuleMesh {
    pub capsule: Capsule,
    pub rings: usize,
    pub longitudes: usize,
    pub latitudes: usize,
    pub uv_profile: CapsuleUvProfile,
}

The Mesh postfix is used for clarity and to avoid naming conflicts, but it could be CapsuleBuilder or CapsuleMeshBuilder too.

It has constructors and builder methods to make configuration easier:

impl CapsuleMesh {
    pub fn new(radius: f32, height: f32, longitudes: usize, latitudes: usize) -> Self { ... }
    pub const fn rings(mut self, rings: usize) -> Self { ... }
    pub const fn longitudes(mut self, longitudes: usize) -> Self { ... }
    pub const fn latitudes(mut self, latitudes: usize) -> Self { ... }
    pub const fn uv_profile(mut self, uv_profile: CapsuleUvProfile) -> Self { ... }

    /// Builds a [`Mesh`] based on the configuration in `self`.
    pub fn build(&self) -> Mesh { ... }
}

Using it looks like this:

// These are equivalent
let mesh = CapsuleMesh::new(0.5, 1.2, 32, 16);
let mesh = Capsule::new(0.5, 1.2).mesh().longitudes(32).latitudes(16);

meshes.add(mesh.build());

Note that build can even be omitted when adding meshes like meshes.add(...) if #10878 gets merged. From<Capsule> and From<CapsuleMesh> are also implemented for Mesh, so into would work as well.

2D meshes now also support different orientations with the Facing enum to face any of the three cartesian axes:

/// The cartesian axis that a [`Mesh`] should be facing upon creation.
/// This is either positive or negative `X`, `Y`, or `Z`.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub enum Facing {
    X = 1,
    Y = 2,
    #[default]
    Z = 3,
    NegX = -1,
    NegY = -2,
    NegZ = -3,
}

// ...

// These are equivalent
let mesh = Rectangle::new(1.0, 0.5).mesh().facing(Facing::X);
let mesh = Rectangle::new(1.0, 0.5).mesh().facing_x();

This is similar to Godot's facing direction for quads and also doubles as a way to flip meshes. Another reason why this is useful is that we can use it to refactor internal mesh logic to be more reusable. For example, we can use CircleMesh for constructing the top and bottom of a CylinderMesh, but just flip the direction the circle is facing.

Below are a few screenshots showing all of the supported shapes with different orientations for 2D shapes.

With UV visualization:

With textures:

With wireframes:

The implementation details of each mesh can be outlined in more detail in their own PRs if I split this PR into granular parts.

Missing mesh implementations

Lines and Direction2d/Direction3d currently don't support meshing because they would require wireframe materials to be rendered (unless we model lines as e.g. capsules or cylinders with thickness) and it's generally better done with gizmos.

Polygon doesn't support meshing because it requires triangulation, which is complex to do well and would most likely require external dependencies. I've tried using earcutr, geo, and lyon_tessellation for this, but none of them seem to support both self-intersections and boolean operations at the same time correctly.

Meshes for these can be implemented later.

API alternatives

The API I opted for is builder-like and has separate structs for the mesh versions of shapes. Some other options I considered include:

• No unified Meshable trait or separate structs, just implement mesh creation for each shape separately like Sphere::new(0.5).uv(longitudes, latitudes)
  • Pro: Very simple and clean at best
  • Pro: No excess data stored :)
  • Con: No data stored :( People might want to pass mesh configurations around
  • Con: All configuration must be passed at once; for something like a capsule, this is four properties!
  • Con: Documentation for configuration properties can not be done cleanly
  • Con: No default values for mesh shapes
  • Con: API is not unified
• Hard-code global defaults, so you can just do Mesh::from(Sphere::new(0.5))
  • Pro: Simple
  • Con: Almost all cons of the previous option
  • Con: No configuration obviously, which is very bad. The resolution, UVs, etc. need to be configurable.

Compare this to the builder API:

• Sphere::new(0.5).mesh().uv(longitudes, latitudes) or SphereMesh::new(radius, SphereKind::Uv { longitudes, latitudes }).build()
  • Pro: Very explicit
  • Pro: Concise. build can even be omitted when adding meshes like meshes.add(...) if Use impl Into<A> for Assets::add #10878 gets merged
  • Pro: Configuration is stored and can be reused
  • Pro: Good documentation is trivial because the properties are actual properties
  • Pro: Easy to extend in the future with more properties
  • Con: Storing configuration isn't always necessary
  • Con: A lot more structs in Bevy

I believe the builder-like API is the ideal middle-ground between simplicity, ease of use, and configurability, and I can't think of many major downsides. Feel free to leave suggestions though!

Open questions

• There are now two ways to do the same thing, for example primitives::Sphere::new(0.5).mesh().uv(longitudes, latitudes) and shapes::SphereMesh::new(radius, SphereKind::Uv { longitudes, latitudes }).build(). Do we want to keep the Meshable API and have these coexist, or should we perhaps remove it? And which approach should we recommend and use in examples?
• Not all primitives have configuration, e.g. cuboids. Should these still have mesh versions like CuboidMesh for the sake of consistency? Personally, I think they should.
• Other concerns?

Next steps

If this approach is approved, I can submit granular PRs to add all of the functionality in this PR in chunks that are easier to review independently. The PRs might be roughly like this:

• Add Meshable trait and mesh creation for 2D primitives
• Implement Mesh creation for Sphere, Cylinder, Capsule, and Torus (the new versions of the "old" 3D shapes)
• Implement Mesh creation for Cone and ConicalFrustum
• Implement Mesh creation for Plane3d
• Remove old mesh shapes in favor of the new primitives

Once all of this is done, we should implement meshing for the remaining primitives, add similar support for gizmos (#10571) and finish other remaining items in #10572.